home *** CD-ROM | disk | FTP | other *** search
/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / languages / dde / _pc / h / help < prev    next >
Encoding:
Text File  |  1992-04-30  |  6.4 KB  |  157 lines
  1. (*
  2.  * Title: h.help
  3.  * Purpose: Provide support for interactive help.
  4.  *
  5.  *)
  6.  
  7. #ifndef __help_h
  8. #define __help_h
  9.  
  10. # ifndef __wimp_h
  11. # include "wimp.h"
  12. # endif
  13.  
  14. # ifndef __event_h
  15. # include "event.h"
  16. # endif
  17.  
  18. # ifndef __dbox_h
  19. # include "dbox.h"
  20. # endif
  21.  
  22. (* ---------------------------- help_process ------------------------------
  23.  * Description:   Returns TRUE if the given event is a menu interactive
  24.  *                help message, which has now been processed.
  25.  *
  26.  * Parameters:    e -- the event to be considered.
  27.  * Returns:       TRUE if the event has now been processed.
  28.  * Other Info:    This should be called by the unknown event handler of
  29.  *                the program. For it to work, you must inform wimpt that
  30.  *                you are aware of Wimps beyond version 2.00. The the rest
  31.  *                of this interface for the handling facilities that this
  32.  *                call invokes.
  33.  *
  34.  *)
  35. function help_process(e : wimp_eventstr_ptr) : boolean; extern;
  36.  
  37.  
  38. (* ---------------------------- help_register_handler ---------------------
  39.  * Description:   Record the handler to be used when help_process is next
  40.  *                called.
  41.  *
  42.  * Parameters:    event_menu_proc -- the handler procedure
  43.  *                handle -- a data handle for the handler procedure
  44.  * Returns:       void
  45.  * Other Info:    This should be called by the menu-maker proc of every 
  46.  *                menu in the program. When help_process is called, the 
  47.  *                most recently installed event_menu_proc handler is 
  48.  *                assumed to be the correct one. Call with NULL as a proc 
  49.  *                if no help is available on this menu.
  50.  *
  51.  *)
  52. procedure help_register_handler(proc : event_menu_proc;
  53.                 handle : pointer) : error; extern;
  54.  
  55.  
  56. (* ---------------------------- help_genmessage ---------------------------
  57.  * Description:   From a given menu hit and prefix, generate a message tag
  58.  *                which is looked up in msgs_lookup. If a message is found
  59.  *                then return it as the interactive help message, and return
  60.  *                TRUE. If not, return FALSE.
  61.  *
  62.  * Parameters:    prefix -- the prefix for all message tags used
  63.  *                hit -- the hit string handed to the event_menu_proc
  64.  *                       registered using help_register_handler
  65.  * Returns:       TRUE if this was a menu help message which has now been
  66.  *                handled
  67.  * Other Info:    The tag for the msgs_lookup call is generated by:
  68.  *                  start with the prefix (maximum length - 20 characters)
  69.  *                  append '0'..'9' or 'a'..'z' for each character in the 
  70.  *                  hit (e.g. character 1 counts as '0', character 10 
  71.  *                  counts as '9', character 11 counts as 'a', etc. More 
  72.  *                  than 35 seems unlikely in a menu of fixed size).
  73.  *                example: original hit 0,1,2 gets translated to string
  74.  *                "\x001\x002\x003", which gets turned into tag "FOO012" for
  75.  *                prefix "FOO". A prefix consisting entirely of upper case
  76.  *                letters is conventional. If there's only one menu tree,
  77.  *                the prefix "HELP" is conventional. For the icon bar,
  78.  *                "IHELP" is conventional.
  79.  *
  80.  *)
  81. function help_genmessage(prefix, hit : string) : error; extern;
  82.  
  83.  
  84. (* ---------------------------- help_simplehandler ------------------------
  85.  * Description:   A simple event_menu_proc suitable for giving to a help
  86.  *                handler.
  87.  *
  88.  * Parameters:    handle -- prefix to pass to help_genmessage
  89.  *                hit -- the menu hit string being processed
  90.  * Returns:       void
  91.  * Other Info:    This will suffice for cases where there are no
  92.  *                alternatives or additional cases to consider. For menus
  93.  *                where the message can vary at run time, a more complex
  94.  *                handler will be required which parses the hit string, or
  95.  *                which calls help_genmessage more than once, or perhaps a
  96.  *                combination of the two.
  97.  *
  98.  *)
  99. procedure help_simplehandler(handle : pointer;
  100.                 hit : string) : error; extern;
  101.  
  102.  
  103. (* ---------------------------- help_dboxrawevents ------------------------
  104.  * Description:   A routine suitable for passing to dbox_raw_eventhandler,
  105.  *                for providing help on dialogue boxes.
  106.  *
  107.  * Parameters:    dbox -- the dbox for which help is being provided
  108.  *                event -- the wimp event being processed
  109.  *                handle -- message tag prefix, really a char*
  110.  * Returns:       TRUE if this was a menu help message which has now been 
  111.  *                handled
  112.  * Other Info:    The handle passed to it should be a message prefix. A
  113.  *                single character suffix may be added to it in the style of
  114.  *                help_genmessage, containing the icon number. If this is
  115.  *                not found (or if no icon is being pointed to), then a the
  116.  *                prefix alone will be used as a message tag. There is no
  117.  *                error if the message is not found.
  118.  *
  119.  *                Typical use:
  120.  *                    dbox d = dbox_new("foo");
  121.  *                    dbox_raw_eventhandler(d, help_dboxrawevents, "FOO");
  122.  *                    dbox_show(d);
  123.  *                    ... now fill in the dbox as normal ...
  124.  *                The test used in implementing this is:
  125.  *                  if (
  126.  *                       (e->e == wimp_ESEND || e->e == wimp_ESENDWANTACK)
  127.  *                       &&
  128.  *                       e->data.msg.hdr.action == wimp_MHELPREQUEST
  129.  *                     )
  130.  *                     ... construct a reply, and send it using help_reply ...
  131.  *                The Messages file should contain:
  132.  *                  FOO:This message will appear in the dbox background.
  133.  *                  FOO0:This message will appear for icon 0 of the dbox
  134.  *                  etc.
  135.  *
  136.  *)
  137. function help_dboxrawevents(d : dbox;
  138.                 event : pointer;
  139.                 handle : pointer) : boolean; extern;
  140.  
  141.  
  142. (* ---------------------------- help_reply ------------------------------
  143.  * Description:   Reply to the help message in wimpt_last_event() with
  144.  *                the (already translated) message provided.
  145.  *
  146.  * Parameters:    m -- help message to display in interactive help window
  147.  * Returns:       void
  148.  * Other Info:    This is useful when creating your own versions of
  149.  *                help_dboxrawevents, which must also handle other events.
  150.  *
  151.  *)
  152. procedure help_reply(m : string); extern;
  153.  
  154. #endif
  155.  
  156. (* end help.h *)
  157.